using System;
using System.Data;

namespace BizElements.Core.ProviderComponents
{
    /// <summary>Executes hierarchical queries.</summary>
	public interface IHierarchicalQueryExecutor
	{
		#region Hierarchical queries and updates.

        /// <summary>Selects rows in the hierarchy under the current entity.</summary>
        /// <param name="conn">Connection-transcation context to use.</param>
        /// <param name="rootEntity">Root entity.</param>
        /// <param name="recursiveRelation">Recursive relation which defines a hierarchy.</param>
        /// <param name="leafFilter">The search condition which restricts the rows returned. Often a criteria which filters out deactivated records.</param>
        /// <param name="sorter">Order by.</param>
        /// <param name="sortOnDb">Specifies whether sorting will take place on database or in DataTable after data has been fetched.</param>
        /// <param name="beginAtLevel">Zero-based index of the first level to fetch. Zero indicates that fetching starts at current entity,
        /// one indicates that fetching starts at the level directly beneath it etc.</param>
        /// <param name="endAtLevel">Zero-based index of the last level to fetch. Zero indicates that fetching ends at current entity,
        /// one indicates that fetching ends at the level directly beneath it etc. <see cref="System.Int32.MaxValue"/> indicates that operation ends at leaf nodes.</param>
        /// <returns>Rows in the hierarchy under the current entity.</returns>
		DataTable SelectTree(IConnectionProvider conn, IEntity rootEntity, DbRelation recursiveRelation, SearchCondition leafFilter, OrderByClause sorter, bool sortOnDb, int beginAtLevel, int endAtLevel);

        /// <summary>Counts the number of levels in the hieararchy starting with the current entity.</summary>
        /// <param name="conn">Connection-transcation context to use.</param>
        /// <param name="rootEntity">Root entity.</param>
        /// <param name="recursiveRelation">Recursive relation which defines a hierarchy.</param>
        /// <returns>Sub-tree depth.</returns>
        int DetermineTreeDepth(IConnectionProvider conn, IEntity rootEntity, DbRelation recursiveRelation);

        /// <summary>Updates rows in the hierarchy under the current entity.</summary>
        /// <param name="conn">Connection-transcation context to use.</param>
        /// <param name="rootEntity">Root entity.</param>
        /// <param name="recursiveRelation">Recursive relation which defines a hierarchy.</param>
        /// <param name="setExpressions">The list of columns to be updated and expressions that compute/contain the new values.</param>
        /// <param name="leafFilter">The search condition which limits the number of rows that are updated. Often a criteria which filters out deactivated records.</param>
        /// <param name="beginAtLevel">Zero-based index of the first level to update. Zero indicates that updating starts at current entity,
        /// one indicates that updating starts at the level directly beneath it etc.</param>
        /// <param name="endAtLevel">Zero-based index of the last level to update. Zero indicates that updating ends at current entity,
        /// one indicates that updating ends at the level directly beneath it etc. <see cref="System.Int32.MaxValue"/> indicates that operation ends at leaf nodes.</param>
        /// <returns>Number of rows affected.</returns>
        int UpdateTree(IConnectionProvider conn, IEntity rootEntity, DbRelation recursiveRelation, UpdateList setExpressions, SearchCondition leafFilter, int beginAtLevel, int endAtLevel);

        /// <summary>Counts rows in the hierarchy under the current entity.</summary>
        /// <param name="conn">Connection-transcation context to use.</param>
        /// <param name="rootEntity">Root entity.</param>
        /// <param name="recursiveRelation">Recursive relation which defines a hierarchy.</param>
        /// <param name="leafFilter">The search condition which restricts the rows counted. Often a criteria which filters out deactivated records.</param>
        /// <param name="beginAtLevel">Zero-based index of the first level to process. Zero indicates that counting starts at current entity,
        /// one indicates that counting starts at the level directly beneath it etc.</param>
        /// <param name="endAtLevel">Zero-based index of the last level to process. Zero indicates that counting ends at current entity,
        /// one indicates that counting ends at the level directly beneath it etc. <see cref="System.Int32.MaxValue"/> indicates that operation ends at leaf nodes.</param>
        /// <returns>Total row count in the hierarchy.</returns>
        int CountTree(IConnectionProvider conn, IEntity rootEntity, DbRelation recursiveRelation, SearchCondition leafFilter, int beginAtLevel, int endAtLevel);

        /// <summary>Retrieves the sum of the column values in the hierarchy under the current entity.</summary>
        /// <param name="conn">Connection-transcation context to use.</param>
        /// <param name="rootEntity">Root entity.</param>
        /// <param name="column">Column. Must be a numeric column that belongs to the current entity's table.</param>
        /// <param name="recursiveRelation">Recursive relation which defines a hierarchy.</param>
        /// <param name="leafFilter">The search condition which restricts the rows processed. Often a criteria which filters out deactivated records.</param>
        /// <param name="beginAtLevel">Zero-based index of the first level to process. Zero indicates that summing starts at current entity,
        /// one indicates that summing starts at the level directly beneath it etc.</param>
        /// <param name="endAtLevel">Zero-based index of the last level to process. Zero indicates that summing ends at current entity,
        /// one indicates that summing ends at the level directly beneath it etc. <see cref="System.Int32.MaxValue"/> indicates that operation ends at leaf nodes.</param>
        /// <returns>Total sum of column values in the hierarchy or <see cref="DBNull.Value"/>.</returns>
        object SumTree(IConnectionProvider conn, IEntity rootEntity, IDbColumn column, DbRelation recursiveRelation, SearchCondition leafFilter, int beginAtLevel, int endAtLevel);

        /// <summary>Retrieves the minimum column value in the hierarchy under the current entity.</summary>
        /// <param name="conn">Connection-transcation context to use.</param>
        /// <param name="rootEntity">Root entity.</param>
        /// <param name="column">Column to compare. Must belong to the current entity's table.</param>
        /// <param name="recursiveRelation">Recursive relation which defines a hierarchy.</param>
        /// <param name="leafFilter">The search condition which restricts the rows processed. Often a criteria which filters out deactivated records.</param>
        /// <param name="beginAtLevel">Zero-based index of the first level to process. Zero indicates that comparison starts at current entity,
        /// one indicates that comparison starts at the level directly beneath it etc.</param>
        /// <param name="endAtLevel">Zero-based index of the last level to process. Zero indicates that comparison ends at current entity,
        /// one indicates that comparison ends at the level directly beneath it etc. <see cref="System.Int32.MaxValue"/> indicates that operation ends at leaf nodes.</param>
        /// <returns>Minimum value or <see cref="DBNull.Value"/>.</returns>
        object MinInTree(IConnectionProvider conn, IEntity rootEntity, IDbColumn column, DbRelation recursiveRelation, SearchCondition leafFilter, int beginAtLevel, int endAtLevel);

        /// <summary>Retrieves the maximum column value in the hierarchy under the current entity.</summary>
        /// <param name="conn">Connection-transcation context to use.</param>
        /// <param name="rootEntity">Root entity.</param>
        /// <param name="column">Column to compare. Must belong to the current entity's table.</param>
        /// <param name="recursiveRelation">Recursive relation which defines a hierarchy.</param>
        /// <param name="leafFilter">The search condition which restricts the rows processed. Often a criteria which filters out deactivated records.</param>
        /// <param name="beginAtLevel">Zero-based index of the first level to process. Zero indicates that comparison starts at current entity,
        /// one indicates that comparison starts at the level directly beneath it etc.</param>
        /// <param name="endAtLevel">Zero-based index of the last level to process. Zero indicates that comparison ends at current entity,
        /// one indicates that comparison ends at the level directly beneath it etc. <see cref="System.Int32.MaxValue"/> indicates that operation ends at leaf nodes.</param>
        /// <returns>Maximum value or <see cref="DBNull.Value"/>.</returns>
        object MaxInTree(IConnectionProvider conn, IEntity rootEntity, IDbColumn column, DbRelation recursiveRelation, SearchCondition leafFilter, int beginAtLevel, int endAtLevel);

		#endregion
	}
}
